feat: ClientContext and secure parameters support #4316

aseering · 2026-01-28T05:27:37Z

Add support for ClientContext and secure parameters.

gemini-code-assist · 2026-01-28T05:28:09Z

Summary of Changes

Hello @aseering, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Java Spanner client library by adding robust support for ClientContext. This feature enables users to embed secure, context-specific metadata with their database requests, facilitating advanced use cases like secure views that require dynamic, user-specific parameters. The implementation provides flexible configuration options and ensures seamless integration and correct behavior across the client's various operational layers.

Highlights

ClientContext Support: Introduced a new ClientContext option within RequestOptions to allow passing side-channel or configuration information to the backend, such as user IDs for parameterized secure views.
Flexible Configuration: The ClientContext can now be configured at multiple levels: as a default in SpannerOptions, on a Connection object, or as an Options parameter for individual queries and updates, with merging logic to handle precedence.
API Integration: Integrated ClientContext propagation throughout the client library, affecting request building in AbstractReadContext, SessionImpl, TransactionRunnerImpl, and various UnitOfWork implementations in the connection layer.
Public API Extension: Added setClientContext and getClientContext methods to the Connection interface, providing a public API for managing the client context on a per-connection basis.
Comprehensive Testing: New and updated unit tests, including a dedicated ClientContextMockServerTest, ensure correct propagation, merging, and persistence of ClientContext across different operations and configuration scenarios.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces support for ClientContext in the Spanner Java client, enabling the use of secure parameters. The changes add a clientContext option at both the global SpannerOptions level and the per-request Options level, with logic to merge them. My review identifies a potential issue where the default ClientContext is not being applied to CommitRequests, which is inconsistent with other request types. I've also included a couple of suggestions to refactor duplicated and verbose code for better maintainability.

I am having trouble creating individual review comments. Click here to see my feedback.

google-cloud-spanner/src/main/java/com/google/cloud/spanner/TransactionRunnerImpl.java (467-470)

The RequestOptions for the CommitRequest are built from per-transaction options but do not appear to merge with the default ClientContext that can be configured on SpannerOptions. This is inconsistent with how BeginTransactionRequest and ExecuteSqlRequest are handled in this PR. This could lead to the ClientContext being unexpectedly missing from commit requests when a default is expected to be applied.

Consider applying the same merge logic used in SessionImpl.beginTransactionAsync here to ensure consistent behavior.

          RequestOptions requestOptions = options.toRequestOptionsProto(true);
          RequestOptions.ClientContext defaultClientContext =
              session.getSpanner().getOptions().getClientContext();
          if (defaultClientContext != null) {
            RequestOptions.ClientContext.Builder clientContextBuilder =
                defaultClientContext.toBuilder();
            if (requestOptions.hasClientContext()) {
              clientContextBuilder.mergeFrom(requestOptions.getClientContext());
            }
            requestOptions =
                requestOptions.toBuilder().setClientContext(clientContextBuilder.build()).build();
          }
          if (!requestOptions.equals(RequestOptions.getDefaultInstance())) {
            requestBuilder.setRequestOptions(requestOptions);
          }

google-cloud-spanner/src/main/java/com/google/cloud/spanner/SessionImpl.java (488-497)

The logic for merging the default ClientContext from SpannerOptions with the request-specific ClientContext is also present in AbstractReadContext.buildRequestOptions. To improve maintainability and reduce code duplication, consider extracting this logic into a shared helper method.

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionImpl.java (2091-2098)

The logic for appending the clientContext as an UpdateOption is a bit verbose. For consistency with mergeQueryRequestOptions, which uses an appendQueryOption helper, consider creating and using a similar helper method like appendUpdateOption.

    if (clientContext != null) {
      options = appendUpdateOption(options, Options.clientContext(clientContext));
    }

This change adds support for ClientContext in Options and ensures it is propagated to ExecuteSql, Read, Commit, and BeginTransaction requests. It aligns with go/spanner-client-scoped-session-state design. - Added RequestOptions.ClientContext to Options. - Refactored request option building to Options.toRequestOptionsProto. - Updated AbstractReadContext, TransactionRunnerImpl, and SessionImpl to use the shared logic. - Added tests.

This change adds support for setting and propagating ClientContext in the Spanner Connection API. ClientContext allows propagating client-scoped session state (e.g., secure parameters) to Spanner RPCs. - Added setClientContext/getClientContext to Connection interface and implementation. - Implemented state propagation from Connection to UnitOfWork and its implementations (ReadWriteTransaction, SingleUseTransaction). - Fixed accidental import removal in OptionsTest.java. - Fixed TransactionRunnerImplTest to correctly verify ClientContext propagation. - Added ClientContextMockServerTest for end-to-end verification.

olavloite · 2026-02-03T09:06:26Z

/gemini review

gemini-code-assist

Code Review

This pull request adds support for secure parameters (ClientContext) to the Spanner Java client. The changes are comprehensive, touching various layers from SpannerOptions down to the connection implementation. The logic for merging default and request-specific client contexts is correctly implemented. The addition of tests, including a mock server test, ensures the new functionality is well-covered. I've included a couple of suggestions to improve the efficiency of building RequestOptions by reducing object creation, and another to improve maintainability by reducing code duplication. Overall, this is a solid feature addition.

google-cloud-spanner/src/main/java/com/google/cloud/spanner/AbstractReadContext.java

google-cloud-spanner/src/main/java/com/google/cloud/spanner/SessionImpl.java

gemini-code-assist · 2026-02-03T09:09:27Z

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionImpl.java

+    if (clientContext != null) {
+      if (options == null || options.length == 0) {
+        options = new UpdateOption[] {Options.clientContext(clientContext)};
+      } else {
+        options = Arrays.copyOf(options, options.length + 1);
+        options[options.length - 1] = Options.clientContext(clientContext);
+      }
+    }


This block for appending clientContext is a bit verbose and duplicates the logic for appending rpcPriority above. This pattern could be extracted into a helper method, similar to appendQueryOption which already exists in this class, to improve readability and reduce code duplication.

For example, you could introduce an appendUpdateOption method:

private UpdateOption[] appendUpdateOption(UpdateOption[] options, UpdateOption append) { if (options == null || options.length == 0) { return new UpdateOption[] {append}; } UpdateOption[] newOptions = Arrays.copyOf(options, options.length + 1); newOptions[newOptions.length - 1] = append; return newOptions; }

Then mergeUpdateRequestOptions could be simplified to:

private UpdateOption[] mergeUpdateRequestOptions(UpdateOption... options) { if (getConnectionPropertyValue(RPC_PRIORITY) != null) { options = appendUpdateOption(options, Options.priority(getConnectionPropertyValue(RPC_PRIORITY))); } if (clientContext != null) { options = appendUpdateOption(options, Options.clientContext(clientContext)); } return options; }

This would make the mergeUpdateRequestOptions method more concise and maintainable.

olavloite

Looks largely good to me with a few nitpicks

Also check whether the last suggestions from Gemini make sense.

google-cloud-spanner/src/main/java/com/google/cloud/spanner/SpannerOptions.java

...d-spanner/src/test/java/com/google/cloud/spanner/connection/ClientContextMockServerTest.java

google-cloud-spanner/src/test/java/com/google/cloud/spanner/OptionsTest.java

google-cloud-spanner/src/test/java/com/google/cloud/spanner/SessionImplTest.java

google-cloud-spanner/src/test/java/com/google/cloud/spanner/TransactionRunnerImplTest.java

aseering requested review from a team as code owners January 28, 2026 05:27

product-auto-label bot added size: l Pull request size is large. api: spanner Issues related to the googleapis/java-spanner API. labels Jan 28, 2026

gemini-code-assist bot reviewed Jan 28, 2026

View reviewed changes

aseering force-pushed the secure-parameters branch from 6081b9e to dccce56 Compare January 29, 2026 18:57

aseering changed the title ~~Secure Parameters support for the Java Client~~ feat: Secure Parameters support for the Java Client Jan 29, 2026

aseering force-pushed the secure-parameters branch 2 times, most recently from 4652157 to 160e1db Compare January 30, 2026 14:04

aseering force-pushed the secure-parameters branch from 160e1db to 4556e81 Compare January 30, 2026 20:42

aseering requested a review from a team as a code owner January 30, 2026 20:42

gemini-code-assist bot reviewed Feb 3, 2026

View reviewed changes

olavloite reviewed Feb 3, 2026

View reviewed changes

olavloite changed the title ~~feat: Secure Parameters support for the Java Client~~ feat: ClientContext and secure parameters support Feb 3, 2026

Address code-review comments

c4fd3ae

aseering force-pushed the secure-parameters branch from 4fc2e27 to c4fd3ae Compare February 3, 2026 15:23

olavloite added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Feb 3, 2026

yoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Feb 3, 2026

olavloite approved these changes Feb 3, 2026

View reviewed changes

olavloite merged commit 6356ef2 into googleapis:main Feb 3, 2026
30 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: ClientContext and secure parameters support #4316

feat: ClientContext and secure parameters support #4316

Uh oh!

aseering commented Jan 28, 2026 •

edited by olavloite

Loading

Uh oh!

gemini-code-assist bot commented Jan 28, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

olavloite commented Feb 3, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist bot Feb 3, 2026

Uh oh!

olavloite left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: ClientContext and secure parameters support #4316

feat: ClientContext and secure parameters support #4316

Uh oh!

Conversation

aseering commented Jan 28, 2026 • edited by olavloite Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Jan 28, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

google-cloud-spanner/src/main/java/com/google/cloud/spanner/TransactionRunnerImpl.java (467-470)

google-cloud-spanner/src/main/java/com/google/cloud/spanner/SessionImpl.java (488-497)

google-cloud-spanner/src/main/java/com/google/cloud/spanner/connection/ConnectionImpl.java (2091-2098)

Uh oh!

olavloite commented Feb 3, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

gemini-code-assist bot Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

olavloite left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aseering commented Jan 28, 2026 •

edited by olavloite

Loading